letter 8.5in 11in\\ @+ \%\%BeginPaperSize: Letter\\ @+ letter\\ @+ \%\%EndPaperSize\\ \\  legal 8.5in 14in\\ @+ ! \%\%DocumentPaperSizes: Legal\\ @+ \%\%BeginPaperSize: Legal\\ @+ legal\\ @+ \%\%EndPaperSize \noindent Note that you can even include structured comments in the configuration file! When \.{dvips has a paper format name given on the command line, it looks for a match by the {\it name; when it has a \.{papersize special, it looks for a match by dimensions. The first match found (in the order the paper size information is found in the configuration file) is used. If nothing matches, a warning is printed and the first paper size given is used, so the first paper size should always be the default. The dimensions must match within a quarter of an inch. Landscape mode for all of the paper sizes are automatically supported. If your printer has a command to set a special paper size, then give dimensions of \.{0in 0in; the PostScript code that sets the paper size can refer to the dimensions the user requested as \.{hsize and \.{vsize; these will be macros defined in the PostScript that return the requested size in default PostScript units. Note that virtually all of the PostScript commands you use here are device dependent and degrade the portability of the file; that is why the default first paper size entry should not send any PostScript commands down (although a structured comment or two would be okay). See the supplied {\tt config.ps file for a more realistic example.

\O a: Conserve memory by making three passes over the \.{dvi file instead of two and only loading those characters actually used. Generally only useful on machines with a very limited amount of memory, like some PCs.

\o e num: Set the maximum drift parameter to {\it num dots (pixels) as explained above. \^{maxdrift

\O f: Run as a filter by default. \^{filter

\o h name: Add {\it name as a PostScript header file to be downloaded at the beginning. \^{header

\o i num: Make each section be a separate file, and set the maximum number of pages in a given file to {\it num. Under certain circumstances, \.{dvips will split the document into ‘sections’ to be processed independently; this is most often done for memory reasons. Using this option tells \.{dvips to place each section into a separate file; the new file names are created by replacing the suffix of the supplied output file name with a three-digit sequence number. This is essentially a combination of the command line options \.{-i and \.{-S; see the documentation for these options for more information.

\o m num: The value {\it num is the virtual memory available for fonts and strings in the printer. \^{memory Default is 180000. This value must be accurate if memory conservation and document splitting is to work correctly. To determine this value, send the following file to the printer: {\parindent=40pt\cmd{\%! Hey, we’re PostScript\\ /Times-Roman findfont 30 scalefont setfont 144 432 moveto\\ vmstatus exch sub 40 string cvs show pop showpage \noindent Note that the number returned by this file is the total memory free; it is often a good idea to tell \.{dvips that the printer has somewhat less memory. This is because many programs download permanent macros that can reduce the memory in the printer. In general, a memory size of about \.{300000 is plenty, since \.{dvips can automatically split a document if required. It is unfortunate that PostScript printers with much less virtual memory still exist. Some systems or printers can dynamically increase the memory available to a PostScript interpreter, in which case this file might return a ridiculously low number; the NeXT computer is such a machine. For these systems, a value of one million works well.

\o o name: \^{output The default output file is set to {\it name. As above, it can be a pipe. Useful in printer-specific configuration files to redirect the output to a particular printer queue.

\o p name: The file to examine for PostScript font aliases is {\it name. It defaults to {\tt psfonts.map. This option allows different printers to use different resident fonts. If the name starts with a ‘{\tt +’ character, then the rest of the name (after any leading spaces) is used as an additional map file; thus, it is possible to have local map files pointed to by local configuration files that append to the global map file.

\O q: Run in quiet mode by default. \^{quiet

\O r: Reverse the order of pages by default. \^{reverse

\O s: Enclose the entire document in a global save/restore pair by default. Not recommended, but useful in some environments; this breaks the conformance of the document to the Adobe PostScript structuring conventions.

\o D num: Set the vertical and horizontal resolution to {\it num \^{resolution dots per inch. Useful in printer-specific configuration files.

\o E command: Executes the command listed; can be used to get the current date into a header file for inclusion, for instance. Possibly dangerous; in many installations this may be disabled, in which case a warning message will be printed if the option is used.

\o H path: The (colon-separated) path to search for PostScript header \^{header files is {\it path.

\O K: Filter comments out of included PostScript files; see the description above for more information.

\o M mode: Set {\it mode as the \MF\ mode to be used when generating fonts. This is \^{{\tt MakeTeXPK \^{{\MF passed along to \.{MakeTeXPK and overrides mode derivation from the base resolution.

\O N: Disable PostScript comments by default.

\o O offset: Move the origin by a certain amount. The {\it offset is a comma-separated pair of dimensions, such as \.{.1in,-.3cm (in the same syntax as used in the \.{papersize special). The origin of the page is shifted from the default position (of one inch down, one inch to the right from the upper left corner of the paper) by this amount.

\o P path: The (colon-separated) path to search for bitmap \.{pk font files is {\it path. The \.{TEXPKS environment variable will override this. \^{{\tt TEXPKS \^{{\tt pk If a \.{\% character is found in {\it path, the following substitutions will be made, and then a search will be made for the resulting filenames. A \.{\%f is replaced by the font name. A \.{\%d is replaced by the font size in dots per inch. A \.{\%p is replaced by the font family; this is always \.{pk. A \.{\%m is replaced by the font mode; this is the mode given in the \.{M option.

\o R num num $\ldots$: Sets up a list of default resolutions to search for \.{pk fonts, if the \^{{\tt pk requested size is not available. The output will then scale the font found using PostScript scaling to the requested size. Note that the resultant output will be ugly, and thus a warning is issued. To turn this off, use a line with just the \.{R and no numbers.

\o S path: The path to search for special illustrations (Encapsulated PostScript files or psfiles) is {\it path. \^{{\tt TEXINPUTS The \.{TEXINPUTS environment variable will override this.

\o T path: The path to search for the \.{tfm files is {\it path. The \.{TEXFONTS environment variable will override this. \^{{\tt TEXFONTS This path is used for resident fonts and fonts that can’t otherwise be found. It’s usually best to make it identical to the path used by \TeX.

\O U: Turns off a memory-saving optimization; this is necessary for the Xerox 4045 printer, but not recommended otherwise. See the description above for more information.

\o V path: The path to search for virtual font \.{vf files is \^{{\tt vf \^{virtual fonts {\it path. This may be device-dependent if you use virtual fonts to simulate actual fonts on different devices.

\o W string: Sends {\it string to stderr, if a parameter is given; otherwise it cancels another previous message. This is useful in the default configuration file if you want to require the user to specify a printer, for instance, or if you want to notify the user that the resultant output has special characteristics.

\o X num: \^{resolution Set the horizontal resolution to {\it num dots per inch.

\o Y num: \^{resolution Set the vertical resolution to {\it num dots per inch.

\O Z: Compress all downloaded fonts by default, as above.\par

\sec{Automatic Font Generation

One major problem with \TeX\ and the Computer Modern fonts is the huge amount of disk space a full set of high resolution fonts can take. The \.{dvips program solves this problem by creating fonts on demand, so only those fonts that are actually used are stored on disk. At a typical site, less than one-fifth of the full set of Computer Modern fonts are used over a long period, so this saves a great deal of disk space.

Furthermore, the addition of dynamic font generation allows fonts to be used at any size, including typesetter resolutions and extremely huge banner sizes. Nothing special needs to be done; the fonts will be automatically created and installed as needed.

The downside is that it does take a certain amount of time to create a new font if it has never been used before. But once a font is created, it will exist on disk, and the next time that document is printed it will print very quickly.

It is the \.{MakeTeXPK shell script that is responsible for making these \^{{\tt MakeTeXPK fonts. The \.{MakeTeXPK script supplied invokes \MF\ to create the font and then copies the resultant \.{pk file to a world-writable font cache area.

\.{MakeTeXPK can be customized to do other things to get the font. For instance, if you are installing \.{dvips to replace (or run alongside) an existing PostScript driver, and that driver demands \.{gf fonts, you can easily modify \.{MakeTeXPK to invoke \.{gftopk to convert the \.{gf files to \.{pk files for \.{dvips. This provides the same space savings listed above.

Because \.{dvips (and thus \.{MakeTeXPK) is run by a wide variety of users, there must be a system-wide place to put the cached font files. In order for everyone to be able to supply fonts, the directory must be world writable. If your system administrator considers this a security hole, \.{MakeTeXPK can write to \.{/tmp/pk or some such directory, and periodically the cached fonts can be moved to a more general system area. Note that the cache directory must exist on the \.{pk file search path in order for \.{MakeTeXPK to work.

\sec{Path Interpretation

The \.{dvips program needs to read a wide variety of files from a large set of directories. It uses a set of paths to do this. The actual paths are listed in the next section; this section describes how the paths are interpreted.

All path variables are names of directories (path elements), separated by colons. Each path element can be either the literal name of a directory or one of the \.{\tilde forms common under UNIX. If a path element is a single tilde, \^{UNIX it is replaced by the contents of the environment variable \.{HOME, which \^{{\tt HOME is normally set to the user’s home directory. If the path element is a tilde followed by anything, the part after the tilde is interpreted as a user name, and his home directory is fetched from the system password file and used as the real path element.

Where environment variables can override paths, an additional path element form is allowed. If a path element is the empty string, it is replaced with the system defaults. Thus, to search the user’s home directory, followed by the system default paths, assuming the current shell is \.{csh, the following command would be used: \cmd{setenv TEXINPUTS \tilde: \noindent This is a path of two elements. The first is the user’s home directory. The second path element is the empty string, indicating that the system defaults should be searched.

The ‘system defaults’ as defined here means the strings set in the \.{Makefile before compilation, rather than any defaults set in \.{config.ps or printer-specific configuration files. This is to prevent path blowup, where more and more directories are added to the path by each level of configuration file.

\sec{Environment Variables

The \.{dvips program reads a certain set of environment variables to configure its operation. The path variables are read after all configuration files are read, so they override values in the configuration files. (The \.{TEXCONFIG variable, of course, is read before the configuration files.) The rest are read as needed.

Note that all defaults supplied here are just as supplied in the provided {\tt Makefile; they will almost certainly have been changed during installation at your particular site.

\descenv HOME,{\rm no default This environment variable is automatically set by the shell and is used to replace any occurrences of \.{\tilde in a path.

\descenv MAKETEXPK,{MakeTeXPK \%n \%d \%b \%m This environment variable sets the command to be executed to create a missing font. A \%n is replaced by the base name of the font to be created (such as \.{cmr10); a \%d is replaced by the resultant horizontal resolution of the font; a \%b is replaced by the horizontal resolution at which \.{dvips is currently generating output, and any \%m is replaced by a string that \MF\ can use as the right hand side of an assignment to \.{mag to create the desired font at the proper resolution. If a mode for \MF\ is set in a configuration file, that is automatically appended to the command before execution. Note that these substitutions are different than the ones performed on PK paths.

\descenv PRINTER,{\rm no default This environment variable is read to determine which default printer configuration file to read in. Note that it is the responsibility of the configuration file to send output to the proper print queue, if such functionality is desired.

\descenv TEXFONTS,{/LocalLibrary/Fonts/TeXFonts/tfm:/usr/lib/tex/fonts/tfm This is where \.{tfm files are searched for. A \.{tfm file only \^{{\tt tfm needs to be loaded if the font is a resident (PostScript) font or if for some reason no \.{pk file could be found.

\descenv TEXPKS,{/LocalLibrary/Fonts/TeXFonts/pk:/usr/lib/tex/fonts/pk This environment variable is a path on which to search for \.{pk fonts. Certain substitutions are performed if a percent sign is found anywhere \^{{\tt pk in the path. A {\tt\%d is replaced by the resolution at which the font is desired; a {\tt\%f is replaced by the base file name of the font (such as {\tt cmr10); a {\tt\%m is replaced by the \MF\ mode for this font; a {\tt\%p is replaced by {\tt pk; and finally, {\tt\%\% is replaced by a single literal {\tt\%.

\descenv TEXINPUTS,{.:..:/usr/lib/tex/inputs This environment variable is used to find PostScript figures when they are included.

\descenv TEXCONFIG,{.:/usr/lib/tex/ps This environment variable sets the directories to search for configuration files, including the system-wide one. Using this single environment variable and the appropriate configuration files, it is possible to set up the program for any environment. (The other path environment variables can thus be redundant.)

\descenv VFFONTS,{.:/usr/lib/tex/fonts/vf This environment variable sets where \.{dvips looks for virtual fonts. A correct virtual font path is essential if PostScript fonts are to be used.

\sec{Other Bells And Whistles

For special effects, if any of the macros \.{bop-hook, \.{eop-hook, \.{start-hook, or \.{end-hook \^{{\tt bop-hook \^{{\tt eop-hook \^{{\tt start-hook \^{{\tt end-hook are defined in the PostScript \.{userdict, they will be executed at the beginning of a page, end of a page, start of the document, and end of a document, respectively. When these macros are executed, the default PostScript coordinate system and origin is in effect. Such macros can be defined in headers added by the \.{-h option or the \.{header= special, and might be useful for writing, for instance, DRAFT across the entire page, or, with the aid of a shell script, dating the document. These macros are executed outside of the save/restore context of the individual pages, so it is possible for them to accumulate information, but if a document must be divided into sections because of memory constraints, such added information will be lost across section breaks.

As an example of what can be done, the following special will write a light DRAFT across each page in the document: {\vskip0pt\parskip=0pt\leftskip=20pt\begverb{‘\$ \special{!userdict begin /bop-hook{gsave 200 30 translate 65 rotate /Times-Roman findfont 216 scalefont setfont 0 0 moveto 0.7 setgray (DRAFT) show grestoredef end$endverb

Note that using \.{bop-hook or \.{eop-hook in any way that preserves information across pages will break compliance with the Adobe document structuring conventions, so if you use any such tricks, it is recommended that you also use the \.{-N option to turn off structured comments.

Several of the above tricks can be used nicely together, and it is not necessary that a ‘printer configuration file’ be used only to set printer defaults. For instance, a \.{-P file can be set up to print the date on each page; the particular configuration file will execute a command to put the date into a header file, which is then included with a \.{h line in the configuration file. Note that multiple \.{-P options can be used.

\ifgeneric\else \sec{MS-DOS The MS-DOS version of \.{dvips differs from UNIX in the following ways. \^{MS-DOS \item{$\bullet$ Path separators are \.{; not \.{:. \item{$\bullet$ Directory separators are \.{\ttbackslash not \.{/. \item{$\bullet$ The user’s initialization file is \.{dvips.ini not \.{.dvipsrc. \item{$\bullet$ Pipes to printers are not supported. Output must go to a file. \item{$\bullet$ \.{MakeTeXPk is a batch file. Since MS-DOS has insufficient memory to run both \.{dvips and \MF\ at the same time, this batch file will typically write out a set of commands for running \MF\ later. The \.{maketexp.bat supplied writes out an \.{mfjob file for em\TeX. \item{$\bullet$ Limited em\TeX\ specials. The following ones are supported: {\vskip0pt\parskip=0pt\leftskip=20pt\begverb{‘\$ \special{em:message xxx \special{em:point n \special{em:line a[h|v|p],b[h|v|p] [,width] \special{em:linewidth width \special{em:moveto \special{em:lineto end$endverb \item{ The \.{\ttbackslash special{\char123em:graph xxx{\char125 is not supported. The line cut parameters \.{[h|v|p] of the \.{\ttbackslash special{\char123em:line ...{\char125 command are ignored. Lines are ended with a rounded cap. A maximum of 1613 different point numbers are permitted on each page.

The program \.{dvips can use em\TeX\ font libraries created with the em\TeX\ \.{fontlib /2 option . If a \.{pxl font is found within a font library, \.{dvips will complain, and then ignore the \.{pxl font.

The font library names and directory names can be specified with this configuration file option.

{\options \def\o#1 #2:{{\tt #1 {\it #2: \def\O#1:{{\tt #1: \o L path: The list of \.{fli font libraries to search for bitmap \.{pk font files is {\it path. \^{{\tt fli Fonts are sought first in these libraries and then as single files. Font libraries can be created with em\TeX ’s \.{fontlib; the usual extension is \.{fli. Directories as well as file names can be entered here, the files will be searched for in all these directories. A directory name must have trailing directory separator (\.{/ for UNIX, \.{\ttbackslash for MS-DOS). \par \fi

\sec{Installation

If \.{dvips has not already been installed on your system, the \^{installation following steps are all that is needed.

First update the \.{Makefile—in particular, the paths. Everything concerning \.{dvips can be adjusted in the \.{Makefile. Make sure you set key parameters such as the default resolution, and make sure that the path given for packed pixel files is correct.

Next, check the file name definitions in \.{MakeTeXPK. If you don’t \^{{\tt MakeTeXPK have \MF\ installed, you cannot use \.{MakeTeXPK to automatically generate the fonts; you can, however, modify it to generate \.{pk fonts from \.{gf fonts if you don’t have a full set of \.{pk fonts but do have a set of \.{gf fonts. If you don’t have that, you should probably not install \.{MakeTeXPK at all; this will disable automatic font generation.

Now, check the configuration parameters in \.{config.ps. You should also update the default resolution here. This file is the system-wide configuration file that will be automatically installed. If you are unsure how much memory your PostScript printer has, print the following file: \cmd{\%! Hey, we’re PostScript\\ /Times-Roman findfont 30 scalefont setfont 144 432 moveto\\ vmstatus exch sub 40 string cvs show pop showpage \noindent Note that the number returned by this file is the total memory free; it is often a good idea to tell \.{dvips that the printer has somewhat less memory. This is because many programs download permanent macros that can reduce the memory in the printer. In general, a memory size of about \.{300000 is plenty, since \.{dvips can automatically split a document if required. It is unfortunate that PostScript printers with much less virtual memory still exist. Some systems or printers can dynamically increase the memory available to a PostScript interpreter; for these systems, a value of one million works well.

Next, run \.{make. Everything should compile smoothly. You may need to adjust the compiler options in the \.{Makefile if something goes amiss.

Once everything is compiled, run \.{make install. After this is done, you may want to create a configuration file for each PostScript printer at your site.

If the font caching is considered a security hole, make the ‘cache’ directory be something like \.{/tmp/pks, and \.{cron a job to move the good \.{pk files into the real directory. Or simply disable this feature by not installing \.{MakeTeXPK.

Don’t forget to install the new \.{vf files and \.{tfm files. Note that the \.{tfm files distributed with earlier (pre-5.471) versions of \.{dvips, and all versions of other PostScript drivers, are different.

\sec{Diagnosing Problems

You’ve gone through all the trouble of installing \.{dvips, carefully read all the instructions in this manual, and still can’t get something to work. This is all too common, and is usually caused by some broken PostScript application out there. The following sections provide some helpful hints if you find yourself in such a situation.

In all cases, you should attempt to find the smallest file that causes the problem. This will not only make debugging easier, it will also reduce the number of possible interactions among different parts of the system.

\sub{Debug Options

The \.{-d flag to \.{dvips is very useful for helping to track down certain errors. The parameter to this flag is an integer that tells what errors are currently being tracked. To track a certain class of debug messages, simply provide the appropriate number given below; if you wish to track multiple classes, sum the numbers of the classes you wish to track. The classes are:

$$\vbox{\halign{\hfil #\quad&#\hfil\cr 1&specials\cr2&paths\cr4&fonts\cr8&pages\cr16&headers\cr 32&font compression\cr64&files\cr 128&memory\cr$$

\sub{No Output At All

If you are not getting any output at all, even from the simplest one-character file (for instance, \.{\char92~\char92 bye), then something is very wrong. Practically any file sent to a PostScript laser printer should generate some output, at the very least a page detailing what error occurred, if any. Talk to your system administrator about downloading a PostScript error handler. (Adobe distributes a good one called \.{ehandler.ps.)

It is possible, especially if you are using non-Adobe PostScript, that your PostScript interpreter is broken. Even then it should generate an error message. I’ve tried to work around as many bugs as possible in common non-Adobe PostScript interpreters, but I’m sure I’ve missed a few.

If \.{dvips gives any strange error messages, or compilation on your machine generated a lot of warnings, perhaps the \.{dvips program itself is broken. Carefully check the types in \.{structures.h and the declarations in the \.{Makefile, and try using the debug options to determine where the error occurred.

It is possible your spooler is broken and is misinterpreting the structured comments. Try the \.{-N flag to turn off structured comments and see what happens.

\sub{Output Too Small or Inverted

If some documents come out inverted or too small, your spooler is not supplying an end of job indicator at the end of each file. (This happens a lot on small machines that don’t have spoolers.) You can force \.{dvips to do this with the \.{-F flag, but note that this generates files with a binary character (control-D) in them. You can also try using the \.{-s flag to enclose the entire job in a save/restore pair.

\sub{Error Messages From Printer

If your printer returns error messages, the error message gives very good information on what might be going wrong. One of the most common error messages is \.{bop undefined. This is caused by old versions of Transcript and other spoolers that do not properly parse the setup section of the PostScript. To fix this, turn off structured comments with the \.{-N option, but make sure you get your spooling software updated.

Another error message is \.{VM exhausted. (Some printers indicate this error by locking up; others quietly reset.) This is caused by telling \.{dvips that the printer has more memory than it actually does, and then printing a complicated document. To fix this, try lowering the parameter to \.{m in the configuration file; use the debug option to make sure you adjust the correct file.

Other errors may indicate that the graphics you are trying to include don’t nest properly in other PostScript documents, or any of a number of other possibilities. Try the output on a QMS PS-810 or other Adobe PostScript printer; it might be a problem with the printer itself.

\sub{400 DPI Is Used Instead Of 300 DPI

This common error is caused by not editing the \.{config.ps file to reflect the correct resolution for your site. You can use the debug flags (\.{-d64) to see what files are actually being read.

\sub{Long Documents Fail To Print

This is usually caused by incorrectly specifying the amount of memory the printer has in \.{config.ps; see the description above.

\sub{Including Graphics Fails

The reasons why graphics inclusions fail are too numerous to mention. The most common problem is an incorrect bounding box; read the section on bounding boxes and check your PostScript file. Complain very loudly to whoever wrote the software that generated the file if the bounding box is indeed incorrect.

Another possible problem is that the figure you are trying to include does not nest properly; there are certain rules PostScript applications should follow when generating files to be included. The \.{dvips program includes work-arounds for such errors in Adobe Illustrator and other programs, but there are certainly applications that haven’t been tested.

One possible thing to try is the \.{-K flag, to strip the comments from an included figure. This might be necessary if the PostScript spooling software does not read the structuring comments correctly. Use of this flag will break graphics from some applications, though, since some applications read the PostScript file from the input stream looking for a particular comment.

Any application which generates graphics output containing raw binary (not hex) will probably fail with \.{dvips.

\sub{Can’t Find Font Files

If \.{dvips complains that it cannot find certain font files, it is possible that the paths haven’t been set up correctly for your system. Use the debug flags to determine precisely what fonts are being looked for and make sure these match where the fonts are located on your system.

\sub{Can’t Generate Fonts

This happens a lot if either \.{MakeTeXPK hasn’t been properly edited and installed, or if the local installation of \MF\ isn’t correct. If \.{MakeTeXPK isn’t properly edited or isn’t installed, an error such as \.{MakeTeXPK not found will be printed on the console. The fix is to talk to the person who installed \.{dvips and have them fix this.

If \MF\ isn’t found when \.{MakeTeXPK is running, make sure it is installed on your system. The person who installed \TeX\ should be able to install \MF\ easily.

If \MF\ runs but generates fonts that are too large (and prints out the name of each character as well as just a character number), then your \MF\ base file probably hasn’t been made properly. To make a proper \.{plain.base, assuming the local mode definitions are contained in \.{local.mf (on the NeXT, \.{next.mf; on the Amiga, \.{amiga.mf), type the following command (assuming \.{csh under UNIX): \cmd{localhost> inimf "plain; input local; dump" \noindent Now, copy the \.{plain.base file from the current directory to where the base files are stored on your system.

Note that a preloaded \.{cmbase.base should never be used when creating fonts, and a program such as \.{cmmf should never exist on the system. The macros defined in \.{cmbase will break fonts that do not use \.{cmbase; such fonts include the La\TeX\ fonts. Loading the \.{cmbase macros when they are needed is done automatically and takes less than a second—an insignificant fraction of the total run time of \MF\ for a font, especially when the possibility of generating incorrect fonts is taken into account. If you create the La\TeX\ font {\tt circle10, for instance, with the \.{cmbase macros loaded, the characters will have incorrect widths.

\sec{Using Color with dvips

This new feature of \.{dvips is somewhat experimental so your experiences and comments are welcome. It was added by Jim Hafner, IBM Research, {\tt hafner@almaden.ibm.com, so please direct your comments there. Besides the changes to the code itself, there are additional \TeX\ macro files \.{dpscolor.tex and \.{dpsblack.tex. There are also \.{.sty versions of these files that can be used with La\TeX\ and other similar macro packages. This feature adds one-pass multi-color printing of \TeX\ documents on any color PostScript device.

In this section we describe the use of color from the document preparer’s point of view and then add some simple instructions on installation for the system administrator.

\sub{The Macro Files

All the color macro commands are defined in \.{dpscolor.tex (or \.{dpscolor.sty). To access these macros simply add to the top of your \TeX\ file the command \cmd{\ttbackslash input dpscolor \noindent or, if your document uses style files like La\TeX, add the \.{dpscolor style option as in \cmd{\ttbackslash documentstyle[12pt,dpscolor]\char123article\char125

There are basically two kinds of color macros, ones for local color changes to, say, a few words or even one symbol and one for global color changes. Note that all the color names use a mixed case scheme. There are 68 predefined colors, with names taken primarily from the Crayola crayon box of 64 colors, and one pair of macros for the user to set his own color pattern. More on this extra feature later. You can browse the file \.{dpscolor.tex for a list of the predefined colors. The comments in this file also show a rough correspondence between the crayon names and PANTONEs.

A local color command is in the form \cmd{\ttbackslash ColorName\char123this will print in color\char125 \noindent Here \.{ColorName is the name of a predefined color. As this example shows, this type of command takes one argument which is the text that is to print in the selected color. This can be used for nested color changes since it restores the original color state when it completes. For example, suppose you were writing in green and want to switch temporarily to red, then blue, back to red and restore green. Here is one way that you can do this: \cmd{This text is green but here we are \ttbackslash Red\char123switching to red, \\ \ttbackslash Blue\char123nesting blue\char125, recovering the red\char125\ and back to \\ original green. \noindent In principle there is no limit to the nesting level, but it is not advisable to nest too deep lest you loose track of the color history.

The global color command has the form \cmd{\ttbackslash textColorName \noindent This macro takes no arguments and immediately changes the default color from that point on to the specified color. This of course can be overriden globally by another such command or locally by local color commands. For example, expanding on the example above, we might have \cmd{\ttbackslash textGreen \\ This text is green but here we are \ttbackslash Red\char123switching to red, \\ \ttbackslash Blue\char123nesting blue\char125, recovering the red\char125\ and back to \\ original green.\\ \ttbackslash textCyan \\ The text from here on will be cyan unless \\ \ttbackslash Yellow\char123locally changed to yellow\char125. Now we are back to cyan.

The color commands will even work in math mode and across math mode boundaries. This means that if you have a color before going into math mode, the mathematics will be set in that color as well. More importantly however, in alignment environments like \.{\ttbackslash halign, \.{tabular or \.{eqnarray, local color commands cannot extend beyond the alignment characters.

Because local color commands respect only some environment and deliminator changes besides their own, care must be taken in setting their scope. It is best not to have then stretch too far.

At the present time there are no macros for color environments in La\TeX\ which might have a larger range. This is primarily to keep the \TeX\ and La\TeX\ use compatible.

\sub{User Definable Colors

There are two ways for the user to specify colors not already defined. For local changes, there is the command \.{\ttbackslash Color which takes two arguments. The first argument is a quadruple of numbers between zero and one and specifies the intensity of cyan, magenta, yellow and black (CMYK) in that order. The second argument is the text that should appear in the given color. For example, suppose you want the words “this color is pretty” to appear in a color which is 50\% cyan, 85\% magenta, 40\% yellow and 20\% black. You would use the command \cmd{\ttbackslash Color\char123{.5 .85 .4 .2\char125\char123 this color is pretty\char125

For global color changes, there is a command \.{\ttbackslash textColor which takes one argument, the CMYK quadruple of relative color intensities. For example, if you want the default color to be as above, then the command \cmd{\ttbackslash textColor\char123{.5 .85 .4 .2\char125 \\ The text from now on will be this pretty color \noindent will do the trick.

Making a global color change in the midst of a nested local colors is highly discouraged. Consequently, \.{dvips will give you warning message and do its best to recover by discarding the current color history.

\sub{Subtleties in Using Color

These color macros are defined by use of specialized \.{\ttbackslash special keywords. As such, they are put in the \.{.dvi file only as explicit message strings to the driver. The (unpleasant) result is that certain unprotected regions of the text can have unwanted color side effects. For example, if a color region is split by \TeX\ across a page boundary, then the footers of the current page (e.g., the page number) and the headers of the next page can inherit that color. To avoid this effect globally, users should make sure that these special regions of the text are defined with their own local color commands. For example in \TeX, to protect the header and footer, use \cmd{\ttbackslash headline\char123\ttbackslash Black\char123 My Header\char125\char125 \\ \ttbackslash footline\char123\ttbackslash Black\char123 \ttbackslash hss\ttbackslash tenrm\ttbackslash folio\ttbackslash hss\char125\char125

Of course, in La\TeX, this is much more difficult to do because of the complexity of the macros that control these regions. This is unfortunate, but is somehow inevitable because \TeX\ and La\TeX\ were not written with color in mind.

\sub{Printing in Black/White, after Colorizing

If you have a \TeX\ or La\TeX\ document written with color macros and you want to print it in black and white there are two options. On all (good) PostScript devices, printing a color file will print in corresponding grey-levels. This is useful since in this way you can get a rough idea of where the colors are changing without using expensive color printing devices. The second option is to replace the call to input \.{dpscolor.tex with \.{dpsblack.tex (and similarly for the \.{.sty files). So in the above example, replacing the word \.{dpscolor with \.{dpsblack suffices. This file defines the color macros as no-ops, and so will produce normal black/white printing. By this simple mechanism, the user can switch to all black/white printing without having to ferret out the color commands. Also, some device drivers, particularly non-PostScript ones like screen previewers, will simply ignore the color commands and so print in normal black/white. Hopefully, in the future screen previewers for color displays will be compatible with some form of color support.

\sub{Configuring dvips for Color Devices

To configure dvips for a particular color device you need to fine tune the color parameters to match your devices color rendition. To do this, you will need a PANTONE chart for your device. The header file \.{color.lpro shows a (rough) correspondence between the Crayola crayon names and the PANTONE numbers and also defines default CMYK values for each of the colors. Note that these colors must be defined in CMYK terms and not RGB as \.{dvips outputs PostScript color commands in CMYK. This header file also defines (if they are not known to the interpreter) the PostScript commands \.{setcmykcolor and \.{currentcmykcolor in terms of a RGB equivalent so if your device only understands RGB, there should be no problem.

The parameters set in this file were determined by comparing the PANTONE chart of a Tektronics PHASER printer with the actual Crayola Crayons. Because these were defined for a particular device, the actual color rendition on your device may be very different. There are two ways to adjust this. One is to use the PANTONE chart for your device to rewrite \.{color.lpro prior to compilation and installation. A better alternative, which supports multiple devices, is to add a header file option in the configuration file for each device that defines, in \.{userdict, the color parameters for those colors that need redefining.

For example, if you need to change the parameters defining \.{Goldenrod (approximate PANTONE 109) for your device \.{mycolordev, do the following. In the PANTONE chart for your device, find the CMYK values for PANTONE 109. Let’s say they are \.{\char123\ 0 0.10 0.75 0.03 \char125. Then create a header file named \.{mycolordev.pro with the commands \cmd{userdict begin \\ /Goldenrod \char123\ 0 0.10 0.75 0.03 \char125\ bind def \noindent Finally, in \.{config.mycolordev add the line \cmd{h mycolordev.pro \noindent This will then define \.{Goldenrod in your device’s CMYK values in \.{userdict which is checked before defining it in \.{TeXdict by \.{color.pro.

This mechanism, together with additions to \.{dpscolor.tex and \.{dpsblack.tex (and the \.{.sty files), can also be used to predefine other colors for your users.

\bye

This document was generated on December 11, 2024 using texi2html 5.0.